docs: add lock file section to the resolver docs #15587
Conversation
Adds some documentation about how lockfiles work to the resolver section, particularly regarding when lock files exist in library dependencies. Effectively re-adds an updated section of docs that was lost here: https://github.com/rust-lang/cargo/pull/12382/files#diff-197a732275c32bdbdb079bdd92ac8a4ba585ee556ea978e9e661804eb76ce9eeL117-L121 Related to this Zulip thread https://rust-lang.zulipchat.com/#narrow/channel/246057-t-cargo/topic/cargo.20lock.20in.20dependency/with/519679182
rustbot
added
A-documenting-cargo-itself
|
|
||
| ## `Cargo.lock` lock-files | ||
|
|
||
| The `Cargo.lock` file provides deterministic builds at different times and on |
There was a problem hiding this comment.
There are some other places the book mentions Cargo.lock
- https://doc.rust-lang.org/nightly/cargo/appendix/glossary.html
- https://doc.rust-lang.org/nightly/cargo/guide/cargo-toml-vs-cargo-lock.html#cargotoml-vs-cargolock
- https://doc.rust-lang.org/nightly/cargo/faq.html#why-have-cargolock-in-version-control
- The previous paragraph.
it is a bit duplicate everywhere. We might want some level of consolidation.
| Dependancy resolution is not run when cargo reads from `Cargo.lock`. | ||
|
|
||
| Not all cargo commands use `Cargo.lock` by default. Examples include | ||
| `cargo install` and `cargo update`.In these cases, `--locked` can usually be |
There was a problem hiding this comment.
This is a bit off. cargo update would always consult the existing Cargo.lock, especially when doing a partial update.
| The `Cargo.lock` file provides deterministic builds at different times and on | ||
| different systems, by ensuring that the exact same dependencies, versions, and | ||
| sources are used as when the `Cargo.lock` file was last generated. | ||
| Dependancy resolution is not run when cargo reads from `Cargo.lock`. |
There was a problem hiding this comment.
This is incorrect. Cargo always performs dependency resolutions and prefers to versions tracked in Cargo.lock.
| ### Libraries with `Cargo.lock` | ||
|
|
||
| Cargo treats `Cargo.lock` files differently when a crate is used as a library | ||
| dependency where an upper level `Cargo.lock` would exist. In these cases cargo will |
There was a problem hiding this comment.
Upper-level / top-level is pretty vague here. Cargo actually ignores any lockfile but the one at the workspace root.
There was a problem hiding this comment.
Perhaps instead, we can just talk about the property of a single view of dependency resolution, so that we don't repeat ourselves and still provide what you originally wanted to know.
### Single view of dependency resolution
When building a package or a workspace, Cargo computes a single,
unified resolution of all dependencies across the entire dependency graph.
This maximizes the reuse of package versions within the resolution process.
Unlike some other package managers, Cargo does not use Cargo.lock files
from dependencies or perform per-dependency resolution.
All resolution is done from the root.
|
@rustbot author |
rustbot
removed
the
S-waiting-on-review
|
Reminder, once the PR becomes ready for a review, use |
rustbot
added
the
S-waiting-on-author
|
For myself, I would try to fit lockfiles into a new section under |
I put it after version numbers and version requirements as it builds on those two topics. Unsure whether this fully resolves the concern from rust-lang#15587 of users coming from other ecosystems that have been burned by library lockfiles affecting them to know that they won't be subject to that.
### What does this PR try to resolve? This fills a whole in our coverage of dependency resolution by specifying how a `Cargo.lock` impacts it. ### How to test and review this PR? I put it after version numbers and version requirements as it builds on those two topics. Unsure whether this fully resolves the concern from #15587 of users coming from other ecosystems that have been burned by library lockfiles affecting them to know that they won't be subject to that.
Did this in #15958. |
Adds some documentation about how lockfiles work to the resolver section, particularly regarding when lock files exist in library dependencies.
Effectively re-adds an updated section of docs that was lost here: https://github.com/rust-lang/cargo/pull/12382/files#diff-197a732275c32bdbdb079bdd92ac8a4ba585ee556ea978e9e661804eb76ce9eeL117-L121
Related to this Zulip thread https://rust-lang.zulipchat.com/#narrow/channel/246057-t-cargo/topic/cargo.20lock.20in.20dependency/with/519679182